About Balmsoft Polyglot

About

Balmsoft Polyglot

Description

Polyglot is a tool for adding localization capabilities to your Delphi application. The Balmsoft Polyglot uses very simple way for localization and it allows even end users to translate an application. It uses INI files for storing translations but at the same time it supports any properties ( TStrings, TCollection, special symbols in labels). The process of translation is as easy as place two components and set three properties. But there is not only run-time components for translation, Balmsoft Polyglot provides very convenient IDE extensions for generation and update translation files. Translation files are text so they suits for source control well. You can track wich rows excetly were changed since last version. It is much harder to corrupt automatic build because you don't need fully replace resources you translate only properties you want to translate and even if there is not translation application will not crash.

At the same time simple translation format allows translate with any text editor, so even your end users will be able to translate application.

Key features

  • Easy-to-start - just place component and provide a couple of properties;
  • Wizard for generation and update translation files;
  • Easy to use translation format (just plain text);
  • Special symbols support;
  • Collections support;
  • TStrings support;
  • Switching between languages in run-time;

New in version 1.3

  • Delphi 4 support;
  • TbsPolyglotTranslator and TbsPolyglotManager provides set of events;
  • "Generate LNG File" Wizard provides additional filtering options (by property name and by property type);
  • Non visual components support ( TActions, TMainMenu);
  • Non API INI file ( no INI file size limitation for Windows 9x);
  • Small bug-fixes and enhancements;

New in version 1.4

  • Resourcestring support (with generation);

New in version 1.5

  • "Exclude properties with specific names" filter in LNG file wizard;
  • "Skip properties that linked to an action" filter in LNG file wizard;
  • TDataModule is supported;
  • MRU list in LNG generation wizard;
  • Small bug-fixes and enhancements;

Compare with resource loaders

There are two main directions in multi language support. The first one is replacing compiled resources with their translated equivalent and the second one is providing additional information for changes specific for some language. Both ways have their own advantages and disadvantages. Classical example of resource loader is Borland Integrated Translation Environment (ITE). It is a great tool and allows you to localize any resource in your application, but there are some points in to use the library like Balmsoft Polyglot:

  • Simple file format allows end-users modify translations and translate an application to their mother language;
  • It is easier to understand and use than resource editors;
  • Any changes to translations can be stored in a version tracking software (it is text file);

For now I can see only one limitation:

  • The Polyglot can not translate forms that reside in other components you use;

So You can try both and choose which one you like best. And the last argument - ITE is supplied only with Delphi Enterprise but our library is free for use. You can not get sources for ITE at all, but you can license sources for Balmsoft Polyglot.


Install Balmsoft Polyglot

Installation

Installation

Installation is very easy just few steps.

Delphi 4

  1. Extract component files. It is better extract into C:\Program Files, so component create folder C:\Program Files\Balmsoft Polyglot\Delphi 4.
  2. Place library files (bsPolyglotD4.bpl and dclbsPolyglotD4.bpl) into your Delphi bin folder. Usually Delphi bin folder is C:\Program Files\Borland\Delphi4\Bin
  3. Open Delphi and choose menu item Tools\Environment options, Environment options dialog appears. Choose library tab page. Add path to *.dcu files into Library path edit (there is a button with ...). If you used default folder then dcu files are placed in C:\Program Files\Balmsoft Polyglot\Delphi 4\Lib. If you have bought a version with sources then add path to sources into Browsing Path. Save settings.
  4. In Delphi choose menu Component\Install package. A window with all installed packages appears. Press Add and choose dclbsPolyglotD4.bpl.
  5. Installation is completed. There are two new components on the palette (TbsPolyglotTranslator and TbsPolyglotManager) and also one more menu item in Project menu ("Generate LNG file").

Very often during installing component (step 4) Delphi reports that bsPolyglotD4.bpl can not be found. This means that you need place bsPolyglotD4.bpl into folder that is included into path variable, for example Delphi bin or system folder like C:\WINNT\System32 (or C:\WINDOWS\System32 for Windows 9x).

Delphi 5

  1. Extract component files. It is better extract into C:\Program Files, so component create folder C:\Program Files\Balmsoft Polyglot\Delphi 5.
  2. Place library files (bsPolyglotD5.bpl and dclbsPolyglotD5.bpl) into your Delphi bin folder. Usually Delphi bin folder is C:\Program Files\Borland\Delphi5\Bin
  3. Open Delphi and choose menu item Tools\Environment options, Environment options dialog appears. Choose library tab page. Add path to *.dcu files into Library path edit (there is a button with ...). If you used default folder then dcu files are placed in C:\Program Files\Balmsoft Polyglot\Delphi 5\Lib. If you have bought a version with sources then add path to sources into Browsing Path. Save settings.
  4. In Delphi choose menu Component\Install package. A window with all installed packages appears. Press Add and choose dclbsPolyglotD5.bpl.
  5. Installation is completed. There are two new components on the palette (TbsPolyglotTranslator and TbsPolyglotManager) and also one more menu item in Project menu ("Generate LNG file").

Very often during installing component (step 4) Delphi reports that bsPolyglotD5.bpl can not be found. This means that you need place bsPolyglotD5.bpl into folder that is included into path variable, for example Delphi bin or system folder like C:\WINNT\System32 (or C:\WINDOWS\System32 for Windows 9x).

Delphi 6

  1. Extract component files. It is better extract into C:\Program Files, so component create folder C:\Program Files\Balmsoft Polyglot\Delphi 6.
  2. Place library files (bsPolyglotD6.bpl and dclbsPolyglotD6.bpl) into your Delphi bin folder. Usually Delphi bin folder is C:\Program Files\Borland\Delphi6\Bin
  3. Open Delphi and choose menu item Tools\Environment options, Environment options dialog appears. Choose library tab page. Add path to *.dcu files into Library path edit (there is a button with ...). If you used default folder then dcu files are placed in C:\Program Files\Balmsoft Polyglot\Delphi 6\Lib. If you have bought a version with sources then add path to sources into Browsing Path. Save settings.
  4. In Delphi choose menu Component\Install package. A window with all installed packages appears. Press Add and choose dclbsPolyglotD6.bpl.
  5. Installation is completed. There are two new components on the palette (TbsPolyglotTranslator and TbsPolyglotManager) and also one more menu item in Project menu ("Generate LNG file").

Very often during installing component (step 4) Delphi reports that bsPolyglotD6.bpl can not be found. This means that you need place bsPolyglotD6.bpl into folder that is included into path variable, for example Delphi bin or system folder like C:\WINNT\System32 (or C:\WINDOWS\System32 for Windows 9x).

Delphi 7

  1. Extract component files. It is better extract into C:\Program Files, so component create folder C:\Program Files\Balmsoft Polyglot\Delphi 7.
  2. Place library files (bsPolyglotD7.bpl and dclbsPolyglotD7.bpl) into your Delphi bin folder. Usually Delphi bin folder is C:\Program Files\Borland\Delphi7\Bin
  3. Open Delphi and choose menu item Tools\Environment options, Environment options dialog appears. Choose library tab page. Add path to *.dcu files into Library path edit (there is a button with ...). If you used default folder then dcu files are placed in C:\Program Files\Balmsoft Polyglot\Delphi 7\Lib. If you have bought a version with sources then add path to sources into Browsing Path. Save settings.
  4. In Delphi choose menu Component\Install package. A window with all installed packages appears. Press Add and choose dclbsPolyglotD7.bpl.
  5. Installation is completed. There are two new components on the palette (TbsPolyglotTranslator and TbsPolyglotManager) and also one more menu item in Project menu ("Generate LNG file").

Very often during installing component (step 4) Delphi reports that bsPolyglotD7.bpl can not be found. This means that you need place bsPolyglotD7.bpl into folder that is included into path variable, for example Delphi bin or system folder like C:\WINNT\System32 (or C:\WINDOWS\System32 for Windows 9x).


License Agreement

LICENSE AGREEMENT

Copyright:

The Balmsoft Polyglot (software) and everything that comes with it is Copyright (C) 2003, by Balmsoft.com. All rights reserved.

OWNERSHIP

The SOFTWARE is owned and copyrighted by Balmsoft. Your license confers no title or ownership in the SOFTWARE and should not be construed as a sale of any right in the SOFTWARE.

Liability disclaimer:

THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS. Balmsoft DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. NEITHER Balmsoft NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE, EVEN IF Balmsoft HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE.

SOME JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATIONS OR EXCLUSION MAY NOT APPLY TO YOU TO THE EXTENT THAT LIABILITY IS BY LAW INCAPABLE OF EXCLUSION OR RESTRICTION.

IN NO EVENT SHALL ANY THEORY OF LIABILITY EXCEED THE LICENSE FEE PAID TO Balmsoft.

Restrictions:

You agree that you will not attempt to reverse compile, modify, translate, or
disassemble the SOFTWARE in whole or in part.

Operating license:

Unregistered version:

You may distribute the unregistered version of software freely, provided that all files are included and remain unmodified and that no extra files have been added to the package.

You may use the unregistered version of the SOFTWARE free of charge for any purposes.

Registered version (with source codes):

Once you have registered, you will receive a personal registered copy via email. This copy may not be copied or lend. You have the non-exclusive right to use registered version of the software only by a single person, on a single computer at a time. YOU MAY use the components and classes from this unit in any your (or your company's) FREEWARE/SHAREWARE or COMMERCIAL application. YOU MAY derive your own components based on components from this unit as you like, but ONLY with UNREGISTERED version of the SOFTWARE and if someone else will decide to use it they will have to register the SOFTWARE too. YOU MAY NOT DISTRIBUTE REGISTERED VERSION OF THE SOFTWARE. IT WILL BE VIOLATION OF INTERNATIONAL COPYRIGHT LAWS.

You may physically transfer the software from one computer to another, provided that the software is used only by a single person, on a single computer at a time. In group projects where multiple persons will use the software, you must purchase an individual license for each member of the group. Use over a "local area network" (within the same locale) is permitted provided that the software is used only by a single person, on a single computer at a time. Use over a "wide area network" (outside the same locale) is strictly prohibited under any and all circumstances.

Back-up and transfer:

You may make one copy of the software solely for "back-up" purposes, as prescribed by international copyright laws. You must reproduce and include the copyright notice on the back-up copy.

Other rights and restrictions:

All other rights and restrictions not specifically granted in this license are reserved by author.


Register Balmsoft Polyglot

Registration

Registration

Why to register

If you register our shareware, you'll:

  1. receive full product sources on purchase;
  2. receive all future product releases for free;
  3. access support and assistance, via E-mail and site, worldwide;

How to register

We use ShareIt! service for payments processing (you will be taken to their site upon filling this form). ShareIt! accepts all possible payment types. Credit cards, money orders, fax, bank transfers. Customers in the US may also place their order by calling the toll-free order number 1-800-903-4152, available 24 hours a day.

After registration you receive full sources. And price is only 29.90 USD. For registration you need visit ShareIt web site and fill order information. To place your order either click here or open www.shareit.com and enter product number 184748. We appreciate your support.

If you have any problems with download please inform us and we will be happy to help you.

Not available. Please contact polyglot@balmsoft.com


Feedback

FEEDBACK

We Welcome Your Comments

Please tell us what you like or dislike about our software. To help us with future versions of our software, we want to know about any corrections or clarifications that you find useful. Many useful features, proposed by users, are already implemented. Please include the following information:
  • The name and version of the software that you are using;
  • Any comments that you have about the software;
  • Your contact information;

The best way to contact us is electronic mail, our address is polyglot@balmsoft.com; ICQ: 71995873. Our time zone is GMT+2 (EST+7)

We appreciate your feedback.


Balmsoft Polyglot overview

Overview

Balmsoft Polyglot overview.

Generally Balmsoft polyglot consists of two parts:

  • Wizard that generates LNG files
  • Components that applies translations at run-time

Components are simple and provides only few public methods so it is easy to use them.

TbsCorePolyglot - core component that actually perform reading from file and translation. There is only one core polyglot and you don't need to create it. It creates automatically. It is not a component for design time it is just a class.

TbsPolyglotManager - stateless component. This component is used for core polyglot configuration during design time. It is also used for connection translators to core polyglot. Usually there is only one manager in an application required.

TbsPolyglotTranslator - just place it on the form and it will translate this form. If all your forms inherit from base form then place translator on your base form and all forms will be translated.

"Generate LNG file" wizard allows automatically create file with all localizable items for project directly from Delphi IDE.


Getting start with Balmsoft Polyglot

Getting start

1. Generate files to be translated

Activate your project in Delphi IDE and choose Projects/Generate LNG file from main menu (this menu command is installed with Balmsoft Polyglot library).

Press ok and wizard store all localizable properties and all resourcestrings from your forms to selected lng file.

2. Add Translation Manager and translators.

Place translation manager on your main form or main data module. Place translator to all froms you wish to translate. All form translators must be linked to this manager.

3. Link translators to manager.

If Manager doesn't appear in the popup menu add reference to main form ( or other place where you placed translation manager ) to uses section in this module. It is required to make this link in design time.

4. Configure translation manager.

Specify LangsDir property (... button brings choose folder dialog ). Depends on LangsDir there will be different set of languages that can be choosen. List of languages are generated based on *.lng file names.

It is possible to specify this properties in runtime:

Example:

//set folder with language files to the same folder as exe file
PolyglotManager.LangsDir := ExtractFileDir(ParamStr(0));
//set current language to French (read from french.lng file)
PolyglotManager.CurrentLang := 'french';

5. Translate files

Copy generated pattern.lng to files with your translations for example french.lng, english.lng, german.lng and so on. and make appropriate modifications. To know more about file format please see File format topic.

6. Run your application

Look all labels are shown from chosen in manager language.

For more information refer Task based topics.


LNG File Format

LNG File Format

Description

LNG File is usual INI file. Each section represents a form to be translated. Sections named as form class ( for example [TForm1]). There is also one more section (initially it is missed but you can add it manually) for storing different strings - it is called [Messages]. Each row consists of item name and value in form <name>=<value>

Simple items

Item name consists of several identifiers separated by '.'. Each identifier represent component name or property name leftmost in name is topmost component in parent/child hierarchy. So if Label1 is placed on Panlel1 in LNG file you will find next row Panel1.Label1.Caption=... . All strings are represented in DFM style format:

  • they are quoted;
  • all special symbols are presented as # and number outside quotations;

For example:

Panel1.Label1.Caption=#9'First line'#10#13'second line.'

Non visual components like TActionList, TAction, TMainMenu and so on are written directly in form section without any prefix:

Action1.Caption='Action1'

TStrings items

TStrings properties are suffixed with Strings identifier so for memo it looks like:

Panel2.Memo1.Lines.Strings='I advise you to try Balmsoft ''Polyglot'' component','It is really easy to use'

Strings are quoted and special symbols are typed directly in strings. Each new line are separated by commas. Is is possible not use quotas for lines without quotation marks and commas but it is better to use quotas for better style. If you need place quote into string just double it (same rule as Delphi string constants).

Collection support

Collection items have not name (mostly) so it is impossible to specify them by name. Index is used for identifying collection items, so for collection item translation looks like:

Panel1.Panel2.DBGrid1.Columns.(2).Title.Caption='Salary'

It means that this row provides translation for property of collection item with index 2 from columns collection.

Resourcestring

All resource strings are placed in the [ResourceStrings] section. Common format for resource string representation is:

65182_bsPolyglotDemoFrm_strMessage1='Test Message.'

  • Leftmost number is resource string ID it can vary in different builds so it is better to update resource strings after using new modules or adding resource strings to your project;
  • name of resource string, this name is created by the Delphi, usually it consists of pas file name and resource string name;
  • string value is encoded as usual string;

Please update your resource strings as often as possible , it uses string id in run-time and it can be changed by delphi. Updating lng file use string name so it change id and keep your translation.

Charset

There is one very important (but not very clear) property charset. It is a property of Font object and it plays big role in Font painting. In the LNG file you need to specify charset as integer number. So I placed here a list of charsets with their integer numbers:

ANSI_CHARSET = 0;
DEFAULT_CHARSET = 1;
SYMBOL_CHARSET = 2;
SHIFTJIS_CHARSET = $80;
HANGEUL_CHARSET = 129;
GB2312_CHARSET = 134;
CHINESEBIG5_CHARSET = 136;
OEM_CHARSET = 255;
JOHAB_CHARSET = 130;
HEBREW_CHARSET = 177;
ARABIC_CHARSET = 178;
GREEK_CHARSET = 161;
TURKISH_CHARSET = 162;
VIETNAMESE_CHARSET = 163;
THAI_CHARSET = 222;
EASTEUROPE_CHARSET = 238;
RUSSIAN_CHARSET = 204;
MAC_CHARSET = 77;
BALTIC_CHARSET = 186;

You can find original constants in Windows.pas


"Generate LNG File" Wizard

Description

This wizard is designed to make it easy to generate file with localizable properties of your project. This wizard works for currently activate project. It is important because there is a chance to delete file with your translations.

Process Forms - Check this check box if you wish to collect localizable properties from forms. If You uncheck this check box than forms sections will not be affected at all neither adding nor removing

Process Resourcestrings - Check this check box if you wish to create/update ResourceStrings section in your LNG file;

Create New File - Create or recreate is already exists specified file and save all localizable properties to it.

Update Existing File - Open file and save only newly added properties. This option very useful for developing version 2 of your software.

Remove Unused Translations - removes unused keys from existing forms (if there is not appropriate form for section then section will stay in file). It is useful if you remove some of your components and you want also remove translations for them

Remove Unused Sections - removes sections that doesn't have correspondent form. ( section [Messages] is not deleted).

Additional filters are applied in next order: (Localizable only) AND ( (name filter) OR (type filter)) .

Localizable only - include in LNG file only properties that registered in Localizable category. ( Please note that this option works only with Delphi 5 or higher).

Include properties with specific name - save only properties with specified name. Name is case insensitive. Please note that this rule applies only to leaf property for example to translate column caption in grid you need add only caption and wizard add next string to LNG file:

Panel1.Panel2.DBGrid1.Columns.(2).Title.Caption = 'Last Name'

Add/Remove buttons allow to add and remove property names to filter.

Include properties with specific type - save only properties with specific types. Please note that this rule doesn't restrict filter by property name rule but add all properties with specific type. This rule also applies only to leaf properties, for example Name is property of Font object and Font is property of Label object. Name is string so Label.Font.Name = 'Arial' will be added to the result LNG file.

Default Filter - resets the filter settings to predefined values.

Exclude properties linked to actions - this means that wizard will not add properties that taken from actions for example control has assigned Action property so wizard will ignore caption and hint property for the button because they will be taken from action and additional line will just duplicate

Exclude properties with specific names - sometimes it is useful to exclude properties with specific names for example MinWidth or MaxWidth are localizable properties but mostly they are not modified during translation;

Please note that filter settings are stored in the Registry on Ok button click.


Task based help

Task based help

Description

Here is few overviews of something like how-to:

  • Obtain list of available languages;
  • Symbols are not displayed correctly;
  • Switch to other language at run-time;
  • Translate third party component property that is not localizable;
  • Resourcestrings are messed;

Obtain list of available languages.

A list of available languages can be obtained from TbsPolyglotManager class through LangCount and Langs properties.

Example:

// fill combo box with available languages
// combo box name is cbLanguages
// PolyglotManager is TbsPolyglotManager component added to the form
var
i: Integer;
begin
  // clear combo box items
  cbLanguages.Items.Clear;
   // enum all languages available in core polyglot and add to combo box
  for i := 0 to PolyglotManager.LangCount - 1 do
  begin
    cbLanguages.Items.Add(PolyglotManager.Langs[i]);
    // set currently selected language as selected item in combo box
    if PolyglotManager.Langs[i] = PolyglotManager.CurrentLang then
      cbLanguages.ItemIndex := i;
  end;
end;

Symbols are not displayed correctly

There are few possible reasons to not display correctly symbols:

  1. Be sure you use right Charset. To see list of Charsets refer LNG File Format or Windows.pas;
  2. It is possible that there is a string like Font.ParentFont=True, so it means that Font ignores your settings and use parent font. So Switch to ParentFont=False;
  3. And finally even if you use right charset there is a possibility that specified font (usually MS Sans Serif) doesn't support chosen charset;
  4. If all above doesn't help it is better contact us for assistance;

Switch to other language at run-time

Switching from one language to other are very simple just change CurrentLang property of TbsPolyglotManager or TbsCorePolyglot. You can obtain an instance of TbsCorePolyglot through class function TbsCorePolyglot.GetCorePolyglot

Translate third party component property that is not localizable

Not all vendors mark properties as Localizable for different reasons (they don't think about localization, component originally developed for Delphi 3 or Delphi 4 and so on). But it is not a problem to translate such property. There are few alternative ways to do it:

Manually add these properties to generated LNG file , see LNG file format for more info (It is easy if it occurs once or twice but it is a big piece of work if this property occurs many times across an application);

Add it to "filter by property name" in Generate LNG file wizard (good way but it is possible that ten other components have property with same name and you don't need to localize them);

The most complex, but the most reliable way is to add properties by your own. Create new design-time package that uses required third party component. And in this package create procedure Register that will register required property in Localizable group.

procedure Register;
begin
  RegisterPropertiesInCategory('Localizable', TBsTaskBar, ['LeftCaption', 'ActiveCaption']);
end;

Resourcestrings are messed

It means that you need update resource string translations, don't worry you will not lose your translations. If you change program code then resourcestring ids can be changed and you need to run "LNG Generate Wizard" to update resource strings. Read more about resourcestrings


Working with resourcestrings

In your code you refer resource strings with names, but after compilation Delphi gives each resource string numeric identifier and the biggest point is that during each compilation it can be different number ids. We have developed special logic to identify your translated string with name and change only id, please refer LNG file format to know more about storing resourcestrings.

After any significant changes (creating new resource strings, intensive using of resource strings in your code or just using some modules) you need update resource strings in LNG file, you can choose update only resource strings without forms and it will be ok (please be carefull don't overwrite file). Updating resource string will not overwrite your translations but update resource strings ids based on names. If you change identifier name or move resource string to other module update wizard will be unable to track it and will remove your translation as unused translation.


TbsCorePolyglot Class

TbsCorePolyglot Class

Syntax

type
  TbsCorePolyglot = class
  public
    constructor Create;
    destructor Destroy; override;
    function GetString(ASection, AStringName: string; ADefault: string = ''): string;
    procedure TranslateForm(AForm: TCustomForm);
    class function GetCorePolyglot: TbsCorePolyglot;
    property LangCount: Integer read;
    property Langs[Index: Integer]: string read;
    property CurrentLang: string read write;
    property LangsDir: string read write;
    property TranslateResourceStrings: Boolean read write;
  end;

Overview

You normally don't need to create an instance of TbsCorePolyglot. You can work directly with core polyglot instance through GetCorePolyglot class function. There are some default values useful to know:

  • Default language folder is ..\Language\;
  • Default language is English;

In your program you can use core polyglot to obtain a list of available languages and get/set currently selected language. Please note that you don't need any additional code to translate forms after changing languages directory or selected language.

Example

// fill combo box with available languages
// combo box name is cbLanguages
var
lPolyglot: TbsCorePolyglot;
i: Integer;
begin
  // clear combo box items
  cbLanguages.Items.Clear;
  // obtain an instance of core polyglot
  lPolyglot := TbsCorePolyglot.GetCorePolyglot;
  // enum all languages available in core polyglot and add to combo box
  for i := 0 to lPolyglot.LangCount - 1 do
  begin
    cbLanguages.Items.Add(lPolyglot.Langs[i]);
    // set currently selected language as selected item in combo box
    if lPolyglot.Langs[i] = lPolyglot.CurrentLang then
      cbLanguages.ItemIndex := i;
  end;
end;

See Also

GetString, TranslateForm, GetCorePolyglot, LangCount, Langs, CurrentLang, LangsDir, TranslateResourceStrings


TbsCorePolyglot.GetString method

TbsCorePolyglot Class

GetString method

The GetString method can be used to obtain a translation for a single string. Usually it is used for translating messages, but it can be used to obtain any translation from LNG file. But in most cases you don't need invoke this function directly because there is a function with same signature in TbsPolyglotManager.

Syntax

function GetString(ASection, AStringName: string; ADefault: string = ''): string;

ASection - section name in the current LNG file to look for message;

AStringName - key name in specified section;

ADefault - will be returned as result if specified string not found;

Result - a value from specified key (AStringName) in specified section (ASection) from currently open LNG file. If specified string is not found then result is ADefault.

Example

// show message from section Messages with key name TestMessage.
MessageDlg(TbsCorePolyglot.GetCorePolyglot.GetString('Messages', 'TestMessage'), mtInformation, [mbOk], 0);


TbsCorePolyglot.TranslateForm method

TbsCorePolyglot Class

TranslateForm method

The TranslateForm method apply translations from currently loaded LNG file to provided Form. Section to read is chosen as Form class name. It is not necessary to invoke this function directly because this function is invoked by TbsPolyglotTranslator after form loaded from resource or changes to currently selected language has been made.

Syntax

procedure TranslateForm(AForm: TCustomForm);

AForm - a form to be translated;


TbsCorePolyglot.GetCorePolyglot method

TbsCorePolyglot Class

GetCorePolyglot method

The GetCorePolyglot class function provides access to an instance of TbsCorePolyglot. There is one instance of TbsCorePolyglot created automatically in initialization clause of bsCorePolyglot.pas.

Syntax

class function GetCorePolyglot: TbsCorePolyglot;


TbsCorePolyglot.LangCount property

TbsCorePolyglot Class

LangCount property

The LangCount property returns a number of available languages in the Langs property.

Syntax

property LangCount: Integer read;

Example

see example for TbsCorePolyglot.

See also

Langs


TbsCorePolyglot.Langs property

TbsCorePolyglot Class

Langs property

The Langs property is a read only property that allows to access a list of currently available languages. The number of languages can be obtained with LangCount property.

Syntax

property Langs[Index: Integer]: string read;

Index - a zero based index of currently available languages;

Result - a name of language. It is a file name of appropriate LNG file without extension.

Example

see example for TbsCorePolyglot.

See also

LangCount


TbsCorePolyglot.CurrentLang Property

TbsCorePolyglot Class

CurrentLang property

The CurrentLang property allows to manage currently loaded LNG file. It is read/write property so it is possible to change language by simple settings this property to one of values from Langs property.

Syntax

property CurrentLang: string read write

See Also

LangCount, Langs


TbsCorePolyglot.LangsDir property

TbsCorePolyglot Class

LangsDir property

The LangsDir property provides access to the directory in which LNG files are stored. LangsDir stores path to directory with \ at the end you can specify path without final \ then the object adds \ automatically. Please note that changes to LangsDir property can cause changes in Langs, LangCount and CurrentLang properties.

Syntax

property LangsDir: string read write;

Example

// set LNG files directory to the same dir as exe file
TbsCorePolyglot.GetCorePolyglot.LangsDir := ExtractFileDir(ParamStr(0));


TbsCorePolyglot.TranslateResourceStrings property

TbsCorePolyglot Class

TranslateResourceStrings property

The TranslateResourceStrings property allows you enable and disable resource string interception and translation. By default this property is true, so normally you don't need anything, but if you want to prevent resource strings translation you can switch it to false.

Syntax

property TranslateResourceStrings: Boolean read write;


TbsPolyglotManager Class

TbsPolyglotManager Class

Syntax

type
  TbsPolyglotManager = class(TComponent)
  public
    constructor Create(AOwner: TComponent); override;
    destructor Destroy; override;
    procedure TranslateForm(AForm: TCustomForm);
    function GetString(ASection: string; AStringName: string; ADefault: string = ''): string;
    property LangCount: Integer read;
    property Langs[Index: Integer]: string read;
  published
    property LangsDir: string read write;
    property CurrentLang: string read write;
    property CurrentLangChanging: TCurrentLangChangingEvent read write;
    property LangsDirChanging: TLangsDirChangingEvent read write;
    property TranslateResourceStrings: Boolean read write;
    property BeforeAllTranslate: TNotifyEvent read write;
    property AfterAllTranslate: TNotifyEvent read write;
  end;

Overview

Normally you need only one instance of TbsPolyglotManager on your main form or main data module. TbsPolyglotManager is stateless class and it is just like configuration utility for TbsCorePolyglot . Normally you need access to only three items:

LangsDir - get/set a folder which contains LNG files;

Current Lang - set/set currently loaded LNG file;

GetString - read a string from currently loaded LNG file. This function is useful for translating different messages.

CurrentLangChanging - fires before change current language and provides an ability to cancel change;

LangsDirChanging - fires before change folder with LNG files and provides an ability to cancel change;

BeforeAllTranslate - fires after changes to current language or folder with LNG files, but before refreshing translators;

AfterAllTranslate - fires after full retranslate all translators;

See Also

GetString, TranslateForm, CurrentLang, LangsDir, CurrentLangChanging, LangsDirChanging, BeforeAllTranslate, AfterAllTranslate, TranslateResourceStrings, LangCount, Langs


TbsPolyglotManager.GetString method

TbsPolyglotManager Class

GetString method

The GetString method can be used to obtain a translation for a single string. Usually it is used for translating messages, but it can be used to obtain any translation from LNG file.

Syntax

function GetString(ASection, AStringName: string; ADefault: string = ''): string;

ASection - section name in the current LNG file to look for message;

AStringName - key name in specified section;

ADefault - will be returned as result if specified string not found;

Result - a value from specified key (AStringName) in specified section (ASection) from currently open LNG file. If specified string is not found then result is ADefault.

Example

// show message from section Messages with key name TestMessage.
MessageDlg(PolyglotManager.GetString('Messages', 'TestMessage'), mtInformation, [mbOk], 0);


TbsPolyglotManager.TranslateForm method

TbsPolyglotManager Class

TranslateForm method

The TranslateForm method apply translations from currently loaded LNG file to provided Form. Section to read is chosen as Form class name. It is not necessary to invoke this function directly because this function is invoked by TbsPolyglotTranslator after form loaded from resource or changes to currently selected language has been made.

This method simply invokes appropriate method of TbsCorePolyglot.

Syntax

procedure TranslateForm(AForm: TCustomForm);

AForm - a form to be translated;


TbsPolyglotManager.CurrentLang property

TbsPolyglotManager Class

CurrentLang property

The CurrentLang property change the appropriate CurrentLang property in the TbsCorePolyglot. There is a convenient drop-down editor in design time for this property.

Syntax

property CurrentLang: string read write;

Example

// set as current chosen in combo box language.
PolyglotManager.CurrentLang := cbLanguages.Text;

See also

TbsCorePolyglot


TbsPolyglotManager.LangsDir property

TbsPolyglotManager Class

LangsDir property

The LangsDir property provides access to the directory in which LNG files are stored. LangsDir stores path to directory with \ at the end you can specify path without final \ then the object adds \ automatically. This property configure TbsCorePolyglot LangsDir property. There is a user-friendly property editor to modify this property in design time

Syntax

property LangsDir: string read write;

Example

// set LNG files directory to the same dir as exe file
PolyglotManager.LangsDir := ExtractFileDir(ParamStr(0));

See also

TbsCorePolyglot


TbsPolyglotManager.AfterAlllTranslate event

TbsPolyglotManager Class

AfterAllTranslate event

The AfterAllTranslate event occurs after full retranslate. Retranslate all can be invoked by changes to LangsDir or CurrentLang properties

Syntax

property AfterAllTranslate: TNotifyEvent read write;

See also

LangsDir, CurrentLang, BeforeAllTranslate


TbsPolyglotManager.BeforeAllTranslate event

TbsPolyglotManager Class

BeforeAllTranslate event

The BeforeAllTranslate even occurs before full application retranslate, exactly after this event manager notifies all translators to retranslate their form.

Syntax

 property BeforeAllTranslate: TNotifyEvent read write;

See also

LangsDir, CurrentLang, AfterAllTranslate


TbsPolyglotManager.TranslateResourceStrings property

TbsPolyglotManager Class

TranslateResourceStrings property

The TranslateResourceStrings property allows you enable and disable resource string interception and translation. By default this property is true, so normally you don't need anything, but if you want to prevent resource strings translation you can switch it to false.

Syntax

property TranslateResourceStrings: Boolean read write;


TbsPolyglotManager.Langs property

TbsPolyglotManager Class

Langs property

The Langs property is a read only property that allows to access a list of currently available languages. The number of languages can be obtained with LangCount property.

Syntax

property Langs[Index: Integer]: string read;

Index - a zero based index of currently available languages;

Result - a name of language. It is a file name of appropriate LNG file without extension.

See also

LangCount


TbsPolyglotManager.LangCount property

TbsPolyglotManager Class

LangCount property

The LangCount property returns a number of available languages in the Langs property.

Syntax

property LangCount: Integer read;

See also

Langs


TbsPolyglotManager.CurrentLangChanging event

TbsPolyglotManager Class

CurrentLangChanging event

The CurrentLangChanging event fires exactly before changing from one current language to other current language. It occurs event for not successful tries (for example target language is not available).

Syntax

property CurrentLangChanging: TCurrentLangChangingEvent read write;
type
  TCurrentLangChangingEvent = procedure (Sender: TObject; OldLanguage, NewLanguage: string; var Cancel: Boolean) of object;

Set the Cancel parameter to True to prevent Current Language switching.

See also

TbsPolyglotManager


TbsPolyglotManager.LangsDirChanging event

TbsPolyglotManager Class

LangsDirChanging event

The tLangsDirChanging event fires exactly before changing from one folder with LNG files to the other folder with LNG files. It occurs event for not successful tries (for example target folder doesn't exist).

Syntax

property LangsDirChanging: TLangsDirChangingEvent read write;
type
  TLangsDirChangingEvent = procedure (Sender: TObject; OldFolder, NewFolder: string; var Cancel: Boolean) of object;

Set the Cancel parameter to True to prevent Language folder switching.

See also

TbsPolyglotManager


TbsPolyglotTranslator Class

TbsPolyglotTranslator Class

Syntax

type
  TbsPolyglotTranslator = class(TComponent)
  public
    procedure Translate;
    constructor Create(AOwner: TComponent); override;
    destructor Destroy; override;
  published
    property Manager: TbsPolyglotManager read write;
    property BeforeTranslate: TNotifyEvent read write;
    property AfterTranslate: TNotifyEvent read write;
  end;

Overview

TbsPolyglotTranslator is component for translation form which it resides. So simply place it on base form or all localizable forms and assign it manager property to valid manager.

See Also

Manager, Translate, TbsPolyglotManager, BeforeTranslate, AfterTranslate


TbsPolyglotTranslator.Manager property

TbsPolyglotTranslator Class

Manager property

The Manager property provides access to the TbsPolyglotManager component. This property mainly used in design-time. Please note that if Manager property is not assigned to valid manager then Translator will not translate form it resides.

Syntax

property Manager: TbsPolyglotManager read write;

See also

TbsPolyglotManager


TbsPolyglotTranslator.Translate method

TbsPolyglotTranslator Class

Translate method

The Translate method forces to reread a translations based on specified Manager property. Normally You don't need to call this method directly because the component retranslate form on any change automatically.

Syntax

procedure Translate;


TbsPolyglotTranslator.AfterTranslate event

TbsPolyglotManager Class

AfterTranslate event

The AfterTranslate event occurs after execution of Translate method of the translator.

Syntax

property AfterTranslate: TNotifyEvent read write;

Sender is reference to the translator

See also

Translate, BeforeTranslate


TbsPolyglotTranslator.BeforeTranslate event

TbsPolyglotManager Class

BeforeTranslate event

The BeforeTranslate event occurs before executing Translate method of this translator.

Syntax

property BeforeTranslate: TNotifyEvent read write;

Sender is reference to the translator

See also

Translate, AfterTranslate